


CI(1)                    USER COMMANDS                      CI(1)



NAME
     ci - check in RCS revisions

SYNOPSIS
     ci [_o_p_t_i_o_n_s] _f_i_l_e ...

DESCRIPTION
     ci stores new  revisions  into  RCS  files.   Each  pathname
     matching an RCS suffix is taken to be an RCS file.  All oth-
     ers are assumed to be working  files  containing  new  revi-
     sions.   ci  deposits the contents of each working file into
     the corresponding RCS file.   If  only  a  working  file  is
     given, ci tries to find the corresponding RCS file in an RCS
     subdirectory and then in the working file's directory.   For
     more details, see FILE NAMING below.

     For ci to work, the caller's login must  be  on  the  access
     list,  except  if  the access list is empty or the caller is
     the superuser or the owner of the file.   To  append  a  new
     revision  to  an  existing  branch, the tip revision on that
     branch must be locked by the caller.  Otherwise, only a  new
     branch can be created.  This restriction is not enforced for
     the owner of the file if non-strict  locking  is  used  (see
     rcs(1)).  A lock held by someone else may be broken with the
     rcs command.

     Unless the -f option is given, ci checks whether  the  revi-
     sion  to  be  deposited  differs from the preceding one.  If
     not, instead of creating a new revision ci  reverts  to  the
     preceding  one.   To revert, ordinary ci removes the working
     file and any lock; ci -l keeps and ci -u removes  any  lock,
     and  then  they  both generate a new working file much as if
     co -l or co -u had been applied to the  preceding  revision.
     When reverting, any -n and -s options apply to the preceding
     revision.

     For each revision deposited, ci prompts for a  log  message.
     The log message should summarize the change and must be ter-
     minated by end-of-file or by a line containing . by  itself.
     If several files are checked in ci asks whether to reuse the
     previous log message.  If the standard input is not a termi-
     nal,  ci suppresses the prompt and uses the same log message
     for all files.  See also -m.

     If the RCS file does not exist, ci creates it  and  deposits
     the  contents  of  the  working file as the initial revision
     (default number: 1.1).  The access list  is  initialized  to
     empty.   Instead of the log message, ci requests descriptive
     text (see -t below).

     The number _r_e_v of the deposited revision can be given by any
     of  the  options -f, -I, -k, -l, -M, -q, -r, or -u.  _r_e_v may



GNU                  Last change: 1991/10/07                    1






CI(1)                    USER COMMANDS                      CI(1)



     be symbolic, numeric, or mixed.  If _r_e_v is $, ci  determines
     the revision number from keyword values in the working file.

     If _r_e_v is a revision number, it  must  be  higher  than  the
     latest one on the branch to which _r_e_v belongs, or must start
     a new branch.

     If _r_e_v is a branch rather than a revision  number,  the  new
     revision  is  appended  to that branch.  The level number is
     obtained by incrementing the tip  revision  number  of  that
     branch.  If _r_e_v indicates a non-existing branch, that branch
     is created with the initial revision numbered _r_e_v.1.

     If _r_e_v is omitted, ci  tries  to  derive  the  new  revision
     number  from  the  caller's  last  lock.   If the caller has
     locked the tip revision of a branch,  the  new  revision  is
     appended  to  that  branch.   The  new  revision  number  is
     obtained by incrementing the tip revision  number.   If  the
     caller locked a non-tip revision, a new branch is started at
     that revision by incrementing the highest branch  number  at
     that revision.  The default initial branch and level numbers
     are 1.

     If _r_e_v is omitted and the caller has no lock, but  owns  the
     file  and locking is not set to _s_t_r_i_c_t, then the revision is
     appended to the default branch (normally the trunk; see  the
     -b option of rcs(1)).

     Exception: On the trunk, revisions can be  appended  to  the
     end, but not inserted.

OPTIONS
     -r[_r_e_v]
          checks in a revision, releases the corresponding  lock,
          and removes the working file.  This is the default.

          The -r option has an unusual meaning in ci.   In  other
          RCS  commands,  -r  merely specifies a revision number,
          but in ci it also releases a lock and removes the work-
          ing file.  See -u for a tricky example.

     -l[_r_e_v]
          works like -r, except it performs an  additional  co -l
          for  the deposited revision.  Thus, the deposited revi-
          sion is immediately checked out again and locked.  This
          is  useful  for saving a revision although one wants to
          continue editing it after the checkin.

     -u[_r_e_v]
          works like -l, except that the  deposited  revision  is
          not  locked.   This  lets  one  read  the  working file
          immediately after checkin.



GNU                  Last change: 1991/10/07                    2






CI(1)                    USER COMMANDS                      CI(1)



          The -l, -r, and -u options are mutually  exclusive  and
          silently override each other.  For example, ci -u -r is
          equivalent to ci -r because -r overrides -u.

     -f[_r_e_v]
          forces a deposit; the new revision is deposited even it
          is not different from the preceding one.

     -k[_r_e_v]
          searches the working file for keyword values to  deter-
          mine  its  revision  number,  creation date, state, and
          author (see co(1)), and assigns  these  values  to  the
          deposited revision, rather than computing them locally.
          It also generates a default login  message  noting  the
          login  of the caller and the actual checkin date.  This
          option is useful for software distribution.  A revision
          that is sent to several sites should be checked in with
          the -k option at these sites to preserve  the  original
          number, date, author, and state.  The extracted keyword
          values and the default log message  may  be  overridden
          with  the  options  -d, -m, -s, -w, and any option that
          carries a revision number.

     -q[_r_e_v]
          quiet mode; diagnostic output is not printed.  A  revi-
          sion  that  is  not different from the preceding one is
          not deposited, unless -f is given.

     -I[_r_e_v]
          interactive mode; the user is prompted  and  questioned
          even if the standard input is not a terminal.

     -d[_d_a_t_e]
          uses _d_a_t_e for the checkin date and time.  The  _d_a_t_e  is
          specified  in  free format as explained in co(1).  This
          is useful for lying about the checkin date, and for  -k
          if no date is available.  If _d_a_t_e is empty, the working
          file's time of last modification is used.

     -M[_r_e_v]
          Set the modification time on any new working file to be
          the  date  of  the  retrieved  revision.   For example,
          ci -d -M -u _f does not  alter  _f's  modification  time,
          even  if  _f's  contents change due to keyword substitu-
          tion.  Use  this  option  with  care;  it  can  confuse
          make(1).

     -m_m_s_g
          uses the string _m_s_g as the log message  for  all  revi-
          sions checked in.

     -n_n_a_m_e



GNU                  Last change: 1991/10/07                    3






CI(1)                    USER COMMANDS                      CI(1)



          assigns the symbolic name _n_a_m_e to  the  number  of  the
          checked-in  revision.   ci  prints  an error message if
          _n_a_m_e is already assigned to another number.

     -N_n_a_m_e
          same as -n, except that it overrides a previous assign-
          ment of _n_a_m_e.

     -s_s_t_a_t_e
          sets the state of the checked-in revision to the  iden-
          tifier _s_t_a_t_e.  The default state is Exp.

     -t_f_i_l_e
          writes descriptive text from the contents of the  named
          _f_i_l_e  into  the  RCS  file, deleting the existing text.
          The _f_i_l_e may not begin with -.

     -t-_s_t_r_i_n_g
          Write descriptive text from the  _s_t_r_i_n_g  into  the  RCS
          file, deleting the existing text.

          The -t option, in both its forms, has effect only  dur-
          ing  an  initial checkin; it is silently ignored other-
          wise.

          During the initial checkin, if  -t  is  not  given,  ci
          obtains  the  text  from  standard input, terminated by
          end-of-file or by a line containing . by  itself.   The
          user  is prompted for the text if interaction is possi-
          ble; see -I.

          For backward compatibility with older versions of  RCS,
          a bare -t option is ignored.

     -w_l_o_g_i_n
          uses _l_o_g_i_n for the author field of the deposited  revi-
          sion.  Useful for lying about the author, and for -k if
          no author is available.

     -V_n  Emulate RCS version _n.  See co(1) for details.

     -x_s_u_f_f_i_x_e_s
          specifies the suffixes for RCS files.  A nonempty  suf-
          fix  matches  any  pathname  ending  in the suffix.  An
          empty suffix matches any pathname of the form  RCS/_f_i_l_e
          or  _p_a_t_h/RCS/_f_i_l_e.  The -x option can specify a list of
          suffixes separated by /.  For example, -x,v/  specifies
          two  suffixes: ,v and the empty suffix.  If two or more
          suffixes are specified, they are tried  in  order  when
          looking  for  an  RCS file; the first one that works is
          used for that file.  If no RCS file is found but an RCS
          file can be created, the suffixes are tried in order to



GNU                  Last change: 1991/10/07                    4






CI(1)                    USER COMMANDS                      CI(1)



          determine the new RCS file's  name.   The  default  for
          _s_u_f_f_i_x_e_s  is installation-dependent; normally it is ,v/
          for hosts like Unix that permit commas in  file  names,
          and  is  empty  (i.e.  just the empty suffix) for other
          hosts.

FILE NAMING
     Pairs of RCS files and working files  may  be  specified  in
     three ways (see also the example section).

     1) Both the RCS file and the working file  are  given.   The
     RCS  pathname is of the form _p_a_t_h_1/_w_o_r_k_f_i_l_e_X and the working
     pathname is of the  form  _p_a_t_h_2/_w_o_r_k_f_i_l_e  where  _p_a_t_h_1/  and
     _p_a_t_h_2/  are (possibly different or empty) paths, _w_o_r_k_f_i_l_e is
     a filename, and _X is an RCS suffix.  If _X is  empty,  _p_a_t_h_1/
     must be RCS/ or must end in /RCS/.

     2) Only the RCS file is given.  Then  the  working  file  is
     created  in  the  current  directory and its name is derived
     from the name of the RCS file by  removing  _p_a_t_h_1/  and  the
     suffix _X.

     3) Only the working file is given.  Then ci  considers  each
     RCS  suffix  _X  in turn, looking for an RCS file of the form
     _p_a_t_h_2/RCS/_w_o_r_k_f_i_l_e_X or (if the former is not found and _X  is
     nonempty) _p_a_t_h_2/_w_o_r_k_f_i_l_e_X.

     If the RCS file is specified without a path in 1) and 2), ci
     looks for the RCS file first in the directory ./RCS and then
     in the current directory.

     ci reports an error if an attempt to open an RCS file  fails
     for  an  unusual  reason, even if the RCS file's pathname is
     just one of several possibilities.  For example, to suppress
     use  of RCS commands in a directory _d, create a regular file
     named _d/RCS so that casual attempts to use RCS commands in _d
     fail because _d/RCS is not a directory.

EXAMPLES
     Suppose ,v is an RCS suffix and the current  directory  con-
     tains a subdirectory RCS with an RCS file io.c,v.  Then each
     of the following commands check  in  a  copy  of  io.c  into
     RCS/io.c,v as the latest revision, removing io.c.

          ci  io.c;    ci  RCS/io.c,v;   ci  io.c,v;
          ci  io.c  RCS/io.c,v;    ci  io.c  io.c,v;
          ci  RCS/io.c,v  io.c;    ci  io.c,v  io.c;

     Suppose instead that the empty suffix is an RCS  suffix  and
     the  current  directory  contains a subdirectory RCS with an
     RCS file io.c.  The each of the following commands checks in
     a new revision.



GNU                  Last change: 1991/10/07                    5






CI(1)                    USER COMMANDS                      CI(1)



          ci  io.c;    ci  RCS/io.c;
          ci  io.c  RCS/io.c;
          ci  RCS/io.c  io.c;

FILE MODES
     An RCS file created by ci inherits the read and execute per-
     missions  from  the  working  file.   If the RCS file exists
     already, ci preserves its read and execute permissions.   ci
     always turns off all write permissions of RCS files.

FILES
     Several temporary files may be created in the directory con-
     taining  the  working file, and also in the temporary direc-
     tory (see TMPDIR under ENVIRONMENT).  A  semaphore  file  or
     files  are created in the directory containing the RCS file.
     With a nonempty suffix, the semaphore names begin  with  the
     first  character of the suffix; therefore, do not specify an
     suffix whose first character could  be  that  of  a  working
     filename.   With  an  empty  suffix, the semaphore names end
     with _ so working filenames should not end in _.

     ci never changes an  RCS  or  working  file.   Normally,  ci
     unlinks  the  file  and  creates  a  new one; but instead of
     breaking a chain of one or more symbolic  links  to  an  RCS
     file,  it  unlinks the destination file instead.  Therefore,
     ci breaks any hard or symbolic links to any working file  it
     changes;  and  hard  links to RCS files are ineffective, but
     symbolic links to RCS files are preserved.

     The effective user must be able  to  search  and  write  the
     directory  containing the RCS file.  Normally, the real user
     must be able to read the RCS and working files and to search
     and  write  the  directory containing the working file; how-
     ever, some older hosts cannot easily switch between real and
     effective  users,  so  on  these hosts the effective user is
     used for all accesses.  The effective user is  the  same  as
     the  real  user  unless your copies of ci and co have setuid
     privileges.   As  described  in  the  next  section,   these
     privileges  yield  extra security if the effective user owns
     all RCS files and directories, and  if  only  the  effective
     user can write RCS directories.

     Users can control access to RCS files by setting the permis-
     sions of the directory containing the files; only users with
     write access to the directory can use RCS commands to change
     its  RCS  files.  For example, in hosts that allow a user to
     belong to several groups, one can make a group's RCS  direc-
     tories  writable to that group only.  This approach suffices
     for informal projects, but it means that  any  group  member
     can  arbitrarily  change the group's RCS files, and can even
     remove them entirely.  Hence more formal projects  sometimes
     distinguish between an RCS administrator, who can change the



GNU                  Last change: 1991/10/07                    6






CI(1)                    USER COMMANDS                      CI(1)



     RCS files at will, and other project members, who can  check
     in new revisions but cannot otherwise change the RCS files.

SETUID USE
     To prevent anybody but their RCS administrator from deleting
     revisions,  a  set  of users can employ setuid privileges as
     follows.

     o+ Check that the host supports RCS setuid  use.   Consult  a
       trustworthy expert if there are any doubts.  It is best if
       the seteuid() system call  works  as  described  in  Posix
       1003.1a  Draft  5,  because  RCS can switch back and forth
       easily between real and effective users, even if the  real
       user  is root.  If not, the second best is if the setuid()
       system call supports saved setuid (the  {_POSIX_SAVED_IDS}
       behavior  of  Posix  1003.1-1990);  this fails only if the
       real user is root.  If RCS detects any failure in  setuid,
       it quits immediately.

     o+ Choose a user _A to serve as RCS administrator for the  set
       of  users.   Only _A will be able to invoke the rcs command
       on the users' RCS files.  _A should  not  be  root  or  any
       other  user with special powers.  Mutually suspicious sets
       of users should use different administrators.

     o+ Choose a path name _B that will be a directory of files  to
       be executed by the users.

     o+ Have _A set up _B to contain copies of ci and  co  that  are
       setuid  to  _A  by copying the commands from their standard
       installation directory _D as follows:

          mkdir  _B
          cp  _D/c[io]  _B
          chmod  go-w,u+s  _B/c[io]

     o+ Have each user prepend _B to their path as follows:

          PATH=_B:$PATH;  export  PATH  # ordinary shell
          set  path=(_B  $path)  # C shell

     o+ Have _A create each RCS directory _R with write access  only
       to _A as follows:

          mkdir  _R
          chmod  go-w  _R

     o+ If you want to let only certain users read the RCS  files,
       put  the  users into a group _G, and have _A further protect
       the RCS directory as follows:





GNU                  Last change: 1991/10/07                    7






CI(1)                    USER COMMANDS                      CI(1)



          chgrp  _G  _R
          chmod  g-w,o-rwx  _R

     o+ Have _A copy old RCS files (if any) into _R, to ensure  that
       _A owns them.

     o+ An RCS file's access list limits who can check in and lock
       revisions.  The default access list is empty, which grants
       checkin access to anyone who can read the  RCS  file.   If
       you want limit checkin access, have _A invoke rcs -a on the
       file; see rcs(1).  In particular, rcs -e -a_A limits access
       to just _A.

     o+ Have _A initialize any new RCS  files  with  rcs -i  before
       initial checkin, adding the -a option if you want to limit
       checkin access.

     o+ Give setuid privileges only to ci, co,  and  rcsclean;  do
       not give them to rcs or to any other command.

     o+ Do not use other setuid commands to invoke  RCS  commands;
       setuid is trickier than you think!

ENVIRONMENT
     RCSINIT
          options prepended to the argument  list,  separated  by
          spaces.   A  backslash escapes spaces within an option.
          The RCSINIT options are prepended to the argument lists
          of  most  RCS commands.  Useful RCSINIT options include
          -q, -V, and -x.

     TMPDIR
          Name of the  temporary  directory.   If  not  set,  the
          environment   variables  TMP  and  TEMP  are  inspected
          instead and the first value found is taken; if none  of
          them  are  set, a host-dependent default is used, typi-
          cally /tmp.

DIAGNOSTICS
     For each revision, ci prints the RCS file, the working file,
     and the number of both the deposited and the preceding revi-
     sion.  The exit status is zero if and only if all operations
     were successful.

IDENTIFICATION
     Author: Walter F. Tichy.
     Revision Number: 5.9; Release Date: 1991/10/07.
     Copyright 8c9 1982, 1988, 1989 by Walter F. Tichy.
     Copyright 8c9 1990, 1991 by Paul Eggert.

SEE ALSO
     co(1), ident(1), make(1), rcs(1),  rcsclean(1),  rcsdiff(1),



GNU                  Last change: 1991/10/07                    8






CI(1)                    USER COMMANDS                      CI(1)



     rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5)
     Walter  F.  Tichy,  RCS--A  System  for   Version   Control,
     _S_o_f_t_w_a_r_e--_P_r_a_c_t_i_c_e & _E_x_p_e_r_i_e_n_c_e 15, 7 (July 1985), 637-654.




















































GNU                  Last change: 1991/10/07                    9



